package org.xbrlapi.aspects;

import java.io.Serializable;

import org.xbrlapi.utilities.XBRLException;

/**
 * <h2>Label Cache</h2>
 * <p/>
 * <p>
 * This interface defines the capabilities of aspect label caching systems.
 * </p>
 * <p/>
 * <p>
 * Label caching systems are intended to improve the performance of aspect
 * rendering systems by determining aspect and aspect value labels in advance.
 * </p>
 *
 * @author Geoff Shuetrim (geoff@galexy.net)
 */
public interface LabelCache extends Serializable {

    /**
     * @param aspectId     the ID of the aspect - must not be null.
     * @param valueId      The id of the aspect value - must not be null.
     * @param locale       The XML language code - can be null.
     * @param resourceRole The label resource role - can be null.
     * @param linkRole     The link role for the extended link containing the label - can be null.
     * @return the label matching the parameters or null if there is no such label in the cache.
     * @throws XBRLException
     */
    public String getLabel(Class<?> labellerClass, String aspectId, String valueId, String locale, String resourceRole, String linkRole) throws XBRLException;

    /**
     * @param aspectId     the ID of the aspect - must not be null.
     * @param valueId      The id of the aspect value - must not be null.
     * @param locale       The XML language code - can be null.
     * @param resourceRole The label resource role - can be null.
     * @param linkRole     The link role for the extended link containing the label - can be null.
     * @return the label matching the parameters or null if there is no such label in the cache.
     * Fallback labels (those generated by a superclass of the specified aspect labeller) are not returned.
     * @throws XBRLException
     */
    public String getLabelWithoutFallback(Class<?> labellerClass, String aspectId, String valueId, String locale, String resourceRole, String linkRole) throws XBRLException;

    /**
     * Caches the given label, replacing earlier versions of such label in the cache to
     * ensure that there is only ever one label in the cache that matches the selection
     * criteria.
     *
     * @param aspectId        the ID of the aspect - must not be null.
     * @param valueId         The id of the aspect value - must not be null.
     * @param locale          The XML language code - can be null.
     * @param resourceRole    The label resource role - can be null.
     * @param linkRole        The link role for the extended link containing the label - can be null.
     * @param label           The label to cache - must not be null.
     * @param isFallbackLabel true if the label is a fallback label and false otherwise.
     * @throws XBRLException
     */
    public void cacheLabel(Class<?> labellerClass, String aspectId, String valueId, String locale, String resourceRole, String linkRole, String label, boolean isFallbackLabel) throws XBRLException;

}
